Node / meshtastic / Meshtastic-Android / files / .github / workflows / docs-deploy.yml

Displaying Raw • Download

Tff7b72nameTb4b4b4: Ta5d6ffDeployTa5d6ff Ta5d6ffDocumentation

T8b949e# Publishes the main-branch docs snapshot to /main/ (and refreshed Dokka to

T8b949e# /api/) on the persistent gh-pages branch. The site root (latest release)

T8b949e# and /vX.Y.Z/ folders are owned by docs-release.yml and are left untouched.

Tff7b72onTb4b4b4:

Tff7b72pushTb4b4b4:

Tff7b72branchesTb4b4b4: Tb4b4b4[Te6edf3mainTb4b4b4]

Tff7b72pathsTb4b4b4:

T8b949e# Dokka sources (KDoc in source files)

Tb4b4b4- Ta5d6ff'Ta5d6ffandroidApp/src/**Ta5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6ffcore/**/src/**Ta5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6fffeature/**/src/**Ta5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6ffdesktopApp/src/**Ta5d6ff'

T8b949e# Docs site sources

Tb4b4b4- Ta5d6ff'Ta5d6ffdocs/**Ta5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6fffeature/docs/**Ta5d6ff'

T8b949e# Build infrastructure. Module scripts are included because they can add or

T8b949e# drop exported `api` dependencies and reshape source sets, changing the

T8b949e# generated reference without any edit under src/.

Tb4b4b4- Ta5d6ff'Ta5d6ffbuild-logic/**Ta5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6ff**/build.gradle.ktsTa5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6ffsettings.gradle.ktsTa5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6ff.github/workflows/docs-deploy.ymlTa5d6ff'

Tb4b4b4- Ta5d6ff'Ta5d6ffscripts/docs/**Ta5d6ff'

Tff7b72workflow_dispatchTb4b4b4:

Tff7b72permissionsTb4b4b4:

Tff7b72contentsTb4b4b4: Ta5d6ffwrite

T8b949e# Shares the group with docs-release.yml so gh-pages pushes serialize.

T8b949e# cancel-in-progress must stay false: a snapshot deploy must never cancel an

T8b949e# in-flight release publish (GitHub still coalesces queued runs to one).

Tff7b72concurrencyTb4b4b4:

Tff7b72groupTb4b4b4: Ta5d6ffpages

Tff7b72cancel-in-progressTb4b4b4: Ta5d6fffalse

Tff7b72jobsTb4b4b4:

Tff7b72publishTb4b4b4:

Tff7b72ifTb4b4b4: Ta5d6ffgithub.repositoryTa5d6ff Ta5d6ff==Ta5d6ff Ta5d6ff'meshtastic/Meshtastic-Android'

Tff7b72runs-onTb4b4b4: Ta5d6ffubuntu-24.04

Tff7b72timeout-minutesTb4b4b4: Ta5d6ff45

Tff7b72stepsTb4b4b4:

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffCheckout

Tff7b72usesTb4b4b4: Ta5d6ffactions/checkout@v7.0.1

Tff7b72withTb4b4b4:

Tff7b72submodulesTb4b4b4: Ta5d6fftrue

Tff7b72fetch-depthTb4b4b4: Ta5d6ff0

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffGradleTa5d6ff Ta5d6ffSetup

Tff7b72usesTb4b4b4: Ta5d6ff./.github/actions/gradle-setup

Tff7b72withTb4b4b4:

Tff7b72gradle_encryption_keyTb4b4b4: Ta5d6ff${{Ta5d6ff Ta5d6ffsecrets.GRADLE_ENCRYPTION_KEYTa5d6ff Ta5d6ff}}

Tff7b72develocity_access_keyTb4b4b4: Ta5d6ff${{Ta5d6ff Ta5d6ffsecrets.DEVELOCITY_ACCESS_KEYTa5d6ff Ta5d6ff}}

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffSetupTa5d6ff Ta5d6ffRuby

Tff7b72usesTb4b4b4: Ta5d6ffruby/setup-ruby@v1

Tff7b72withTb4b4b4:

Tff7b72ruby-versionTb4b4b4: Ta5d6ff'Ta5d6ff4.0.6Ta5d6ff'

Tff7b72bundler-cacheTb4b4b4: Ta5d6fftrue

Tff7b72working-directoryTb4b4b4: Ta5d6ffdocs

T8b949e# Dokka is the slowest part of this workflow (~14 min) but KDoc changes far

T8b949e# less often than the prose docs. Rebuild /api/ only when something that can

T8b949e# actually change the generated reference was touched; otherwise the existing

T8b949e# /api/ on gh-pages is left in place (the publisher overlays per channel).

T8b949e# Manual runs always rebuild everything, so the diff is only needed on push.

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffDetectTa5d6ff Ta5d6ffDokka-relevantTa5d6ff Ta5d6ffchanges

Tff7b72ifTb4b4b4: Ta5d6ffgithub.event_nameTa5d6ff Ta5d6ff!=Ta5d6ff Ta5d6ff'workflow_dispatch'

Tff7b72usesTb4b4b4: Ta5d6ffdorny/paths-filter@v4

Tff7b72idTb4b4b4: Ta5d6fffilter

Tff7b72withTb4b4b4:

Tff7b72tokenTb4b4b4: Ta5d6ff'Ta5d6ff'

Tff7b72filtersTb4b4b4: Tb4b4b4|

Tff7b72# Positive patterns only. paths-filter evaluates each pattern as an

Tff7b72# independent predicate and ORs them together, so a '!excluded/**'

Tff7b72# entry would match every path outside that dir and make the filter

Tff7b72# always true. The modules in DOKKA_EXCLUDED_MODULES that live under

Tff7b72# these prefixes (:core:konsist) therefore still trigger a rebuild;

Tff7b72# they change rarely enough that the odd wasted run is fine.

Tff7b72dokka:

Tff7b72- 'androidApp/src/**'

Tff7b72- 'core/**/src/**'

Tff7b72- 'feature/**/src/**'

Tff7b72- 'desktopApp/src/**'

Tff7b72# Dokka config, module list and the plugin classpath. '**/build.gradle.kts'

Tff7b72# covers the root script as well as every module's, since a module script

Tff7b72# can change exported `api` deps or source sets with no src/ edit.

Tff7b72- 'build-logic/**'

Tff7b72- '**/build.gradle.kts'

Tff7b72- 'settings.gradle.kts'

Tff7b72- 'gradle/libs.versions.toml'

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffGenerateTa5d6ff Ta5d6ffDocsTa5d6ff Ta5d6ffSiteTa5d6ff Ta5d6ff(mainTa5d6ff Ta5d6ffchannel)

Tff7b72runTb4b4b4: Ta5d6ff./gradlewTa5d6ff Ta5d6ffgenerateDocsBundleTa5d6ff Ta5d6ffvalidateDocsBundleTa5d6ff Ta5d6ffpublishDocsSiteTa5d6ff Ta5d6ff-Pdocs.channel=mainTa5d6ff Ta5d6ff-Pci=true

T8b949e# Dokka (Gradle) and Jekyll (Ruby) are independent — Dokka's output is only

T8b949e# copied in afterwards — so run them concurrently to overlap the two slowest

T8b949e# steps (~14 min Dokka vs ~5 min Jekyll) instead of summing them.

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffBuildTa5d6ff Ta5d6ffDokkaTa5d6ff Ta5d6ff+Ta5d6ff Ta5d6ffJekyllTa5d6ff Ta5d6ffconcurrently

Tff7b72envTb4b4b4:

Tff7b72BUILD_DOKKATb4b4b4: Ta5d6ff${{Ta5d6ff Ta5d6ffsteps.filter.outputs.dokkaTa5d6ff Ta5d6ff==Ta5d6ff Ta5d6ff'true'Ta5d6ff Ta5d6ff||Ta5d6ff Ta5d6ffgithub.event_nameTa5d6ff Ta5d6ff==Ta5d6ff Ta5d6ff'workflow_dispatch'Ta5d6ff Ta5d6ff}}

Tff7b72runTb4b4b4: Tb4b4b4|

Tff7b72set -euo pipefail

Tff7b72BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build \

Tff7b72--source build/_site/main \

Tff7b72--destination build/jekyll_site \

Tff7b72--baseurl /${{ github.event.repository.name }}/main &

Tff7b72jekyll_pid=$!

Tff7b72if [ "$BUILD_DOKKA" = "true" ]; then

Tff7b72./gradlew dokkaGeneratePublicationHtml --no-configuration-cache

Tff7b72else

Tff7b72echo "No Dokka-relevant changes — skipping API reference rebuild."

Tff7b72fi

Tff7b72wait "$jekyll_pid"

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffStageTa5d6ff Ta5d6ffchannels

Tff7b72idTb4b4b4: Ta5d6ffstage

Tff7b72envTb4b4b4:

Tff7b72BUILD_DOKKATb4b4b4: Ta5d6ff${{Ta5d6ff Ta5d6ffsteps.filter.outputs.dokkaTa5d6ff Ta5d6ff==Ta5d6ff Ta5d6ff'true'Ta5d6ff Ta5d6ff||Ta5d6ff Ta5d6ffgithub.event_nameTa5d6ff Ta5d6ff==Ta5d6ff Ta5d6ff'workflow_dispatch'Ta5d6ff Ta5d6ff}}

Tff7b72runTb4b4b4: Tb4b4b4|

Tff7b72set -euo pipefail

Tff7b72mkdir -p build/pages_staging

Tff7b72cp -r build/jekyll_site build/pages_staging/main

Tff7b72channels="main"

Tff7b72if [ "$BUILD_DOKKA" = "true" ]; then

Tff7b72cp -r build/dokka/html build/pages_staging/api

Tff7b72channels="$channels api"

Tff7b72fi

Tff7b72echo "channels=$channels" >> "$GITHUB_OUTPUT"

Tb4b4b4- Tff7b72nameTb4b4b4: Ta5d6ffPublishTa5d6ff Ta5d6fftoTa5d6ff Ta5d6ffgh-pages

Tff7b72runTb4b4b4: Ta5d6ffscripts/docs/publish-to-gh-pages.shTa5d6ff Ta5d6ffbuild/pages_stagingTa5d6ff Ta5d6ff${{Ta5d6ff Ta5d6ffsteps.stage.outputs.channelsTa5d6ff Ta5d6ff}}